<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual describes GNU Stow version 2.3.1
(28 July 2019), a program for managing farms of symbolic links.

Software and documentation is copyrighted by the following:

(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>


(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>


(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>


(C) 2011 Adam Spiers <stow@adamspiers.org>

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.


Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled "GNU General Public License" is included with the
modified manual, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation. -->
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Installing Packages (Stow)</title>

<meta name="description" content="Installing Packages (Stow)">
<meta name="keywords" content="Installing Packages (Stow)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Index.html#Index" rel="index" title="Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="index.html#Top" rel="up" title="Top">
<link href="Deleting-Packages.html#Deleting-Packages" rel="next" title="Deleting Packages">
<link href="Justification-For-Yet-Another-Set-Of-Ignore-Files.html#Justification-For-Yet-Another-Set-Of-Ignore-Files" rel="prev" title="Justification For Yet Another Set Of Ignore Files">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<a name="Installing-Packages"></a>
<div class="header">
<p>
Next: <a href="Deleting-Packages.html#Deleting-Packages" accesskey="n" rel="next">Deleting Packages</a>, Previous: <a href="Ignore-Lists.html#Ignore-Lists" accesskey="p" rel="prev">Ignore Lists</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Installing-Packages-1"></a>
<h2 class="chapter">5 Installing Packages</h2>

<a name="index-installation"></a>
<p>The default action of Stow is to install a package.  This means creating
symlinks in the target tree that point into the package tree.  Stow
attempts to do this with as few symlinks as possible; in other words, if
Stow can create a single symlink that points to an entire subtree within
the package tree, it will choose to do that rather than create a
directory in the target tree and populate it with symlinks.
</p>
<a name="tree-folding"></a><a name="Tree-folding"></a>
<h3 class="section">5.1 Tree folding</h3>
<a name="index-tree-folding"></a>
<a name="index-directory-folding"></a>
<a name="index-folding-trees"></a>
<p>For example, suppose that no packages have yet been installed in
<samp>/usr/local</samp>; it&rsquo;s completely empty (except for the <samp>stow</samp>
subdirectory, of course).  Now suppose the Perl package is installed.
Recall that it includes the following directories in its installation
image:  <samp>bin</samp>; <samp>info</samp>; <samp>lib/perl</samp>; <samp>man/man1</samp>.
Rather than creating the directory <samp>/usr/local/bin</samp> and populating
it with symlinks to <samp>../stow/perl/bin/perl</samp> and
<samp>../stow/perl/bin/a2p</samp> (and so on), Stow will create a
single symlink, <samp>/usr/local/bin</samp>, which points to
<samp>stow/perl/bin</samp>.  In this way, it still works to refer to
<samp>/usr/local/bin/perl</samp> and <samp>/usr/local/bin/a2p</samp>, and fewer
symlinks have been created.  This is called <em>tree folding</em>, since an
entire subtree is &ldquo;folded&rdquo; into a single symlink.
</p>
<p>To complete this example, Stow will also create the symlink
<samp>/usr/local/info</samp> pointing to <samp>stow/perl/info</samp>; the symlink
<samp>/usr/local/lib</samp> pointing to <samp>stow/perl/lib</samp>; and the symlink
<samp>/usr/local/man</samp> pointing to <samp>stow/perl/man</samp>.
</p>
<p>Now suppose that instead of installing the Perl package into an empty
target tree, the target tree is not empty to begin with.  Instead, it
contains several files and directories installed under a different
system-administration philosophy.  In particular, <samp>/usr/local/bin</samp>
already exists and is a directory, as are <samp>/usr/local/lib</samp> and
<samp>/usr/local/man/man1</samp>.  In this case, Stow will descend into
<samp>/usr/local/bin</samp> and create symlinks to
<samp>../stow/perl/bin/perl</samp> and <samp>../stow/perl/bin/a2p</samp> (etc.),
and it will descend into <samp>/usr/local/lib</samp> and create the
tree-folding symlink <samp>perl</samp> pointing to
<samp>../stow/perl/lib/perl</samp>, and so on.  As a rule, Stow only
descends as far as necessary into the target tree when it can create a
tree-folding symlink.  However, this behaviour can be changed via
the <samp>--no-folding</samp> option; see <a href="Invoking-Stow.html#Invoking-Stow">Invoking Stow</a>.
</p>
<a name="Tree-unfolding"></a><a name="Tree-unfolding-1"></a>
<h3 class="section">5.2 Tree unfolding</h3>
<a name="index-splitting-open-folded-trees"></a>
<a name="index-unfolding-trees"></a>
<a name="index-tree-unfolding"></a>
<a name="index-tree-unsplitting"></a>
<p>The time often comes when a tree-folding symlink has to be undone
because another package uses one or more of the folded subdirectories in
its installation image.  This operation is called <em>splitting open</em> or
<em>unfolding</em> a folded tree.  It involves removing the original symlink from
the target tree, creating a true directory in its place, and then populating the
new directory with symlinks to the newly-installed package <em>and</em> to
the old package that used the old symlink.  For example, suppose that
after installing Perl into an empty <samp>/usr/local</samp>, we wish to
install Emacs.  Emacs&rsquo;s installation image includes a <samp>bin</samp>
directory containing the <samp>emacs</samp> and <samp>etags</samp> executables,
among others.  Stow must make these files appear to be installed
in <samp>/usr/local/bin</samp>, but presently <samp>/usr/local/bin</samp> is a
symlink to <samp>stow/perl/bin</samp>.  Stow therefore takes the
following steps:  the symlink <samp>/usr/local/bin</samp> is deleted; the
directory <samp>/usr/local/bin</samp> is created; links are made from
<samp>/usr/local/bin</samp> to <samp>../stow/emacs/bin/emacs</samp> and
<samp>../stow/emacs/bin/etags</samp>; and links are made from
<samp>/usr/local/bin</samp> to <samp>../stow/perl/bin/perl</samp> and
<samp>../stow/perl/bin/a2p</samp>.
</p>
<a name="Ownership"></a>
<h3 class="section">5.3 Ownership</h3>
<a name="index-ownership"></a>
<p>When splitting open a folded tree, Stow makes sure that the
symlink it is about to remove points inside a valid package in the
current stow directory.  <em>Stow will never delete anything
that it doesn&rsquo;t own</em>.  Stow &ldquo;owns&rdquo; everything living in the
target tree that points into a package in the stow directory.  Anything
Stow owns, it can recompute if lost: symlinks that point into a package in
the stow directory, or directories that only contain symlinks that stow
&ldquo;owns&rdquo;.   Note that by this definition, Stow doesn&rsquo;t &ldquo;own&rdquo; anything
<em>in</em> the stow directory or in any of the packages.
</p>
<a name="Conflicts-during-installation"></a>
<h3 class="section">5.4 Conflicts during installation</h3>
<a name="index-conflicts"></a>
<a name="index-installation-conflicts"></a>
<p>If Stow needs to create a directory or a symlink in the target
tree and it cannot because that name is already in use and is not owned
by Stow, then a <em>conflict</em> has arisen.  See <a href="Conflicts.html#Conflicts">Conflicts</a>.
</p>

<hr>
<div class="header">
<p>
Next: <a href="Deleting-Packages.html#Deleting-Packages" accesskey="n" rel="next">Deleting Packages</a>, Previous: <a href="Ignore-Lists.html#Ignore-Lists" accesskey="p" rel="prev">Ignore Lists</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
